HTTP connector service contract

Using HTTP connector, an application on Process Platform uses services that are available over HTTP or HTTPS. These services are HTTP services such as web services or REST-based services. Since Process Platform follows SOAP protocol, the web services can be consumed by Process Platform in a format that is understandable by the Platform. HTTP connector transforms the SOAP-based application and Platform messages to the format expected by the service and the other way round.

Response from the external HTTP service will be added to the webservice response root as xml, after the necessary transformations. If the HTTP service response has namespace associated with it, this namespace will be preserved , when adding it to the webservice response. If HTTP response does not have any namespace associated with it, then the namespace of the root element of webservice response will become the namespace of the HTTP response.

When a service is presented to the Process Platform, it must follow the following web service implementation protocol.

Tag Name Description Mandatory Example

implementation

This is the root tag of any service executed by HTTP connector. It must have an attribute called type with value HTTP.

Attributes

type: value is HTTP
xmlns: http://httpconnector.opentext.com/1.0/implementation

Yes

<implementation type="HTTP" xmlns="http://httpconnector.opentext.com/1.0/implementation">
   ....
</implementation>

connection-id

ID of the connection to be used for executing the request. This ID must be present in the http connections configuration stored in the XML store.

Yes

<implementation type="HTTP" xmlns="http://httpconnector.opentext.com/1.0/implementation" xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/">
    <connection-id>TEST-CONNECTION</connection-id>
....
</implementation>

uri

The URI of the external service. This value must be relative to the URI given in the http connection configuration stored in the XML store. The URI can also be parametrized.

Web service implementation depicting a static URI

<implementation type="HTTP" xmlns="http://httpconnector.opentext.com/1.0/implementation" xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/">
    <connection-id>TEST-CONNECTION</connection-id>
    <uri>/v2/rss/testrest</uri>
    ....
</implementation>

Web service implementation depicting a parameterized URI

<implementation type="HTTP" xmlns="http://httpconnector.opentext.com/1.0/implementation" xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/">
    <connection-id>TEST-CONNECTION</connection-id>
    <http-method>GET</http-method>
    <uri>/v2/rss/testrest/{0}</uri>
    <request-handler class="com.opentext.applicationconnector.httpconnector.impl.RestRequestHandler">
        <uri-parameters>
            <parameter type="xpath">./Username</parameter>
        </uri-parameters>
    </request-handler>
    ....
</implementation>

While processing the request, the actual URI is constructed by substituting the value of the Username parameter from the request.

http-method

Denotes the HTTP method to be used while executing the service. HTTP connector supports the following methods:

GET
POST
PUT
DELETE

Note: The default value is POST.

<implementation type="HTTP" xmlns="http://httpconnector.opentext.com/1.0/implementation" xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/">
    <connection-id>TEST-CONNECTION</connection-id>
    <uri>/v2/rss/testrest</uri>
    <http-method>GET|POST|PUT|DELETE</http-method>
    ....
</implementation>

clean-response-body

If true, the response SOAP body contents get cleared. This is useful only for methods which cannot return the response method element. The default value is false.

<implementation type="HTTP" xmlns="http://httpconnector.opentext.com/1.0/implementation" xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/">
    <connection-id>TEST-CONNECTION</connection-id>
    <uri>/v2/rss/testrest</uri>
    <http-method>GET|POST|PUT|DELETE</http-method>
    <clean-response-body>true</clean-response-body>
    ....
</implementation>

request-handler

Provides various details on request processing. This includes the handlers which process the request, transformation which needs to be applied on request XML. The parameters required for the request are as follows:

Attributes

class: The fully qualified class name of the handler which can process the request. HTTP connector, by default, can access web services and REST-based services. Each of these require separate handlers.
- If the service is web service, then use com.opentext.applicationconnector.httpconnector.impl.StandardRequestHandler
- If the service is REST based, then use com.opentext.applicationconnector.httpconnector.impl.RestRequestHandler

Child elements

uri-parameters
xslt
req-headers
root-xpath

Yes

Web service implementation for Non-REST API

<implementation type="HTTP" xmlns="http://httpconnector.opentext.com/1.0/implementation" xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/">
    <connection-id>TEST-CONNECTION</connection-id>
    <uri>/v2/rss/testnonrest</uri>
    <request-handler class="com.opentext.applicationconnector.httpconnector.impl.StandardRequestHandler">
        ....
    </request-handler>
    ....
</implementation>

Web service implementation for REST API

<implementation type="HTTP" xmlns="http://httpconnector.opentext.com/1.0/implementation" xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/">
    <connection-id>TEST-CONNECTION</connection-id>
    <uri>/v2/rss/testrest</uri>
    <request-handler class="com.opentext.applicationconnector.httpconnector.impl.RestRequestHandler">
        ....
    </request-handler>
    ....
</implementation>

uri-parameters

Gives details about the list of parameters required by the service. Each parameter is represented by the parameter element.

Child elements

parameter

<implementation type="HTTP" xmlns="http://httpconnector.opentext.com/1.0/implementation" xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/">
    <connection-id>TEST-CONNECTION</connection-id>
    <uri>/v2/rss/testrest</uri>
    <request-handler class="com.opentext.applicationconnector.httpconnector.impl.RestRequestHandler">
        <uri-parameters>
            <parameter type="xpath">./Username</parameter>
            <parameter type="Fixed">./Tags/Tag</parameter>
        </uri-parameters>
    </request-handler>
    ....
</implementation>

parameter

Represents one parameter.

Attributes

type: Type denotes the type of value given in the parameter, which can bean XPath, fixed, connection-parameter or connection-uri.

WebService implementation illustrating connection-uri and connection-parameter

XMLStore connection configuration

<implementation xmlns="http://httpconnector.opentext.com/1.0/implementation" xmlns:c="http://schemas.cordys.com/cws/1.0" xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/" type="HTTP">
  <connection-id>JENKINS</connection-id>
  <http-method>GET</http-method>
  <uri>/jenkins/job/httpconnector-test-wip-linux/{0}/{1}</uri>
  <request-handler class="com.opentext.applicationconnector.httpconnector.impl.RestRequestHandler">
    <uri-parameters>
      <parameter type="connection-parameter">firstBuild</parameter>
	  <parameter type="connection-uri" />
    </uri-parameters>
  </request-handler>
  <response-handler class="com.opentext.applicationconnector.httpconnector.impl.RestResponseHandler" />
  <valid-response-code>200</valid-response-code>
</implementation>

<configurations xmlns="http://httpconnector.opentext.com/1.0/configuration">
  <connections>
    <connection id="JENKINS">
      <url>http://buildmaster-hyd.vanenburg.com/api/json</url>
      <parameters>
        <parameter type="STRING">
          <name>firstBuild</name>
          <value>102</value>
        </parameter>
      </parameters>
    </connection>
  </connections>
</configurations>

As mentioned in the above example, the connection configuration from the XML store has a STRING typed parameter with name firstBuild having parameter value as 102. If you intend to read this value and set it as one of the parameter values for the web service implementation, the following construct is effective.

<parameter type="connection-parameter">firstBuild</parameter>

In the similar way, you can use the following construct to read the relative path of the connection URL for the given connection-id from the connection configuration stored in the XML store.

<parameter type="connection-uri" />

Eventually, for the above example, the effective URI is http://buildmaster-hyd.vanenburg.com/jenkins/job/httpconnector-test-wip-linux/102/api/json

102 is the connection-parameter value while the /api/json is connection-uri parameter.

req-headers

Represents custom HTTP headers. These custom HTTP headers are set in the request before an outbound call is made.

Child elements

header

<implementation type="HTTP" xmlns="http://httpconnector.opentext.com/1.0/implementation" xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/">
    <connection-id>TEST-CONNECTION</connection-id>
    <uri>/v2/rss/testrest</uri>
    <request-handler class="com.opentext.applicationconnector.httpconnector.impl.RestRequestHandler">
        <uri-parameters>
            <parameter type="xpath">./Username</parameter>
            <parameter type="Fixed">./Tags/Tag</parameter>
        </uri-parameters>
        <req-headers>
           <header name="x-ms-version">2012-03-01</header>
           <header name="Content-Type">application/xml</header>
        </req-headers>
    </request-handler>
....
</implementation>

root-xpath

HTTP methods PUT and POST accepts payload and denotes the XPath to be applied to extract the payload from a request and send as part of PUT or POST.

<implementation xmlns="http://httpconnector.opentext.com/1.0/implementation">
    <request-handler class="com.opentext.applicationconnector.httpconnector.impl.RestRequestHandler">
        <root-xpath>payload/GetTasksForUser</root-xpath>
    </request-handler>
</implementation>

response-handler

Provides various details on handling from the service which is accessed. This includes the handlers which can process the response, the transformation which needs to be applied on the response, and so on.

Attributes

class: The fully qualified class name of the handler which can process the response. com.opentext.applicationconnector.httpconnector.impl.StandardResponseHandler com.opentext.applicationconnector.httpconnector.impl.RestResponseHandler

Child elements

xslt

<implementation type="HTTP" xmlns="http://httpconnector.opentext.com/1.0/implementation" xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/">
    <connection-id>TEST-CONNECTION</connection-id>
    <uri>/v2/rss/testrest</uri>
    <request-handler class="com.opentext.applicationconnector.httpconnector.impl.RestRequestHandler">
        <uri-parameters>
            <parameter type="xpath">./Username</parameter>
            <parameter type="xpath">./Tags/Tag</parameter>
        </uri-parameters>
    </request-handler>
    <response-handler class="com.opentext.applicationconnector.httpconnector.impl.StandardResponseHandler">
        <xslt xmlstore="xslts/response.xslt"/>
    </response-handler>
....
</implementation>

valid-response-xpath

XPath expression for validating the response.

valid-response-code

HTTP response code for validating the response.

namespaces

Holds the namespace prefix mappings that must be used.

Child elements

binding

binding

Represents one namespace binding with prefix and URI.

Attributes

uri
prefix

xslt

The path to XSLT in the XML store used to transform request and response. This can be mentioned both for request handling and response handling.

<implementation type="HTTP" xmlns="http://httpconnector.opentext.com/1.0/implementation" xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/">
    <connection-id>TEST-CONNECTION</connection-id>
    <uri>/v2/rss/testrest</uri>
    <request-handler class="com.opentext.applicationconnector.httpconnector.impl.RestRequestHandler">
        <xslt xmlstore="xslts/request.xslt"/>
        
    </request-handler>
    <response-handler class="com.opentext.applicationconnector.httpconnector.impl.StandardResponseHandler">
        <xslt xmlstore="xslts/response.xslt"/>
    </respo nse-handler>
....
</implementation>

Note: For an example on how to develop web services using the HTTP connector, see Developing web services using the HTTP connector.

pp108 : HTTP connector service contract

HTTP connector service contract